---
title: Repositories
description: Official Zoi repositories, mirrors, and repository tiers.
---

This page explains Zoi's official repositories and mirrors, and how package repositories are organized by tier.

## Official project and package database

- Source code (Zoi)
  - Primary: [GitLab](https://gitlab.com/Zillowe/Zillwen/Zusty/Zoi)
  - Mirrors: [GitHub](https://github.com/Zillowe/Zoi), [Codeberg](https://codeberg.org/Zillowe/Zoi)

- Packages database (Zoidberg)
  - Primary: [GitLab](https://gitlab.com/Zillowe/Zillwen/Zusty/Zoidberg)
  - Mirrors: [GitHub](https://github.com/Zillowe/Zoidberg), [Codeberg](https://codeberg.org/Zillowe/Zoidberg)

## Managing the Package Database Registry

The package database is the core git repository that Zoi clones to `~/.zoi/pkgs/db`. This repository contains all the package definitions organized into tiers. While you can manage which repositories inside the database are active using `zoi repo`, you can also change the URL of the entire database registry itself using `zoi sync`.

This is useful if you want to use a mirror or a completely different package database.

| Command                         | Description                                                                                  |
| ------------------------------- | -------------------------------------------------------------------------------------------- |
| `zoi sync set <url-or-keyword>` | Sets the package database registry URL. Keywords: `default`, `gitlab`, `github`, `codeberg`. |
| `zoi sync show`                 | Displays the current registry URL.                                                           |

### Examples

```sh
# Show the current registry URL
zoi sync show

# Set the registry to the official GitHub mirror
zoi sync set github

# Set the registry to a custom URL
zoi sync set https://my-custom-registry.com/Zoidberg.git
```

### Automatic Fallback

To improve reliability, Zoi can automatically try syncing from the mirrors defined in the `mirrors-git` list of the `repo.yaml` file if your configured primary registry is unavailable.

- **`zoi sync --fallback`**: If the sync fails, Zoi will attempt to use the mirrors one by one until it succeeds.
- **`zoi update`**: The `update` command uses this fallback mechanism by default to ensure that package updates are as reliable as possible.

## Repository tiers

Zoi organizes packages into tiers. Use these to decide where a package belongs and to assess stability.

| Repository  | Purpose                                                                           |
| ----------- | --------------------------------------------------------------------------------- |
| `core`      | Essential packages and libraries; very common and well-maintained.                |
| `main`      | Important packages that don't fit in `core` but are essential for most users.     |
| `extra`     | New or niche packages; less common and may be less actively maintained.           |
| `community` | User-submitted packages. New entries start here and may graduate to higher tiers. |
| `test`      | Testing ground for new Zoi features and packages prior to release.                |
| `archive`   | Archived packages that are no longer maintained.                                  |
| `zillowe`   | Zillowe: Zillowe's own official packages.                                         |

Note: Packages from `community`, `test`, and `archive` may carry higher risk. Zoi prints warnings where appropriate.

## Managing Active Repositories

The `zoi repo` command manages which repositories from the package database are active. Active repositories are searched during package operations like `install` and `search`.

| Command                       | Description                                                                                       |
| ----------------------------- | ------------------------------------------------------------------------------------------------- |
| `zoi repo add`                | Add an official repo by name or a git repo by URL (interactive if no args).                       |
| `zoi repo rm <name>`          | Remove a repository from the active list.                                                         |
| `zoi repo list` (alias: `ls`) | Show active repositories from config. Use `zoi repo list all` to show all available repositories. |
| `zoi repo git ls`             | List cloned git repositories under `~/.zoi/pkgs/git`.                                             |
| `zoi repo git rm <repo>`      | Remove a cloned git repository directory.                                                         |

### Examples

```sh
# Add a repository interactively
zoi repo add

# Add official repositories by name
zoi repo add core
zoi repo add main
zoi repo add community

# Add by git URL (cloned under ~/.zoi/pkgs/git/ and used via @git/<repo>/<pkg>)
zoi repo add https://github.com/YourOrg/my-zoi-repo.git

# Remove and list
zoi repo rm community
zoi repo list
zoi repo list all
zoi repo git ls
zoi repo git rm my-zoi-repo
```

### Direct Git Repository Installation

In addition to adding a git repository to your local configuration with `zoi repo add`, you can install a package directly from a remote git repository using the `--repo` flag with `zoi install`.

```sh
# Install from a GitHub repository
zoi install --repo Zillowe/Hello

# Install from a GitLab repository
zoi install --repo gl:Zillowe/Hello

# Install from a Codeberg repository
zoi install --repo cb:Zillowe/Hello
```

This works if the target repository has a `zoi.yaml` file in its root. The `package` field in this file can specify a package name (e.g. `hello`), a path to a `.pkg.lua` file within the repository, or a URL to a `.pkg.lua` file. This provides a quick way to install packages from git repositories without permanently adding them to your configuration.

**Provider Prefixes:**

- `gh:` or `github:` for GitHub (this is the default if no prefix is given).
- `gl:` or `gitlab:` for GitLab.
- `cb:` or `codeberg:` for Codeberg.

## Installing from a specific repository

- Top-level repository:

```sh
zoi install @community/htop
```

- Nested repository path (e.g. platform-specific):

```sh
zoi install @core/linux/amd64/nvidia-driver
```

To install a package from your custom git repository, use the `@git/` prefix, followed by the repository name and the package name.

```sh
# Install from the root of 'my-zoi-repo'
zoi install @git/my-zoi-repo/package

# Install from a nested directory within the git repo
zoi install @git/my-zoi-repo/path/to/package
```

For creating packages, see [Creating Packages](/docs/zds/zoi/creating-packages).

For publishing packages, see [Publishing Packages](/docs/zds/zoi/publishing-packages).

## Nel Package Registry

All packages from the official `core`, `main`, `extra`, and `community` repositories are browsable and searchable on the [Nel Registry](https://nel.zillowe.qzz.io). This provides a convenient way to discover new packages and view their details online.

## The `repo.yaml` file

A Zoi package registry is defined by a `repo.yaml` file at its root. This file contains metadata about the repository, such as its name, description, and the URLs for its git repository and pre-built packages.

Here are the fields available in `repo.yaml`:

| Field         | Type     | Description                                                                                                                                      |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`        | `string` | The name of the repository.                                                                                                                      |
| `description` | `string` | A short description of the repository.                                                                                                           |
| `repo-git`    | `string` | The primary git URL for the package database. This is where Zoi will clone the repository from.                                                  |
| `mirrors-git` | `list`   | (Optional) A list of fallback git URLs to use if the primary `repo-git` fails. Zoi will try them in order.                                       |
| `repo-pkg`    | `string` | (Optional) The URL template for a pre-built package registry. Zoi will try to download pre-built packages from here before building from source. |
| `mirrors-pkg` | `list`   | (Optional) A list of fallback URLs for the pre-built package registry.                                                                           |

The `repo-pkg` and `mirrors-pkg` URLs can contain the following placeholders, which Zoi will replace at runtime:

- `{os}`: The operating system (e.g. `linux`, `macos`, `windows`).
- `{arch}`: The CPU architecture (e.g. `amd64`, `arm64`).
- `{version}`: The version of the package.
- `{package}`: The name of the package.

### Example

```yaml
name: Zoi repo
description: The official Zoi package repository.
repo-git: https://gitlab.com/Zillowe/Zillwen/Zusty/Zoiberg.git
mirrors-git:
  - https://github.com/Zillowe/Zoidberg.git
  - https://codeberg.org/Zillowe/Zoidberg.git
repo-pkg: https://zoi.zillowe.qzz.io/pkgs/{os}/{arch}/{version}/{package}
mirrors-pkg:
  - https://zoi.zilo.qzz.io/pkgs/{os}/{arch}/{version}/{package}
```
